1. Introduction
1.1. Project/Component Working Name:

GlassFish Server Open Source Edition 3.1.2 - Support for Storing Transaction Logs in a Database for Recovery after Crash of a Stand-alone Instance or a Delegated Transaction Recovery in a Cluster One Pager

1.2. Name(s) and e-mail address of Document Author(s)/Supplier:

Marina Vatkina: mvatkina@java.net
1.3. Date of This Document:

10/28/11

2. Project Summary
2.1. Project Description:

Achieve functional parity between storing transaction logs in a database and a file system.
2.2. Risks and Assumptions:

Risks: complete parity is not achieved.
Assumptions:
a) Upgrade from an existing table (if the users made it work in v2.x) is not supported.
b) Extra manual setup will be required for some databases.

3. Problem Summary
3.1. Problem Area:

Transaction recovery is an important part of XA transaction support. Currently storing transaction logs in a database has a very limited support - only recovery on a single instance from another database crush is supported. I.e. there is no support for delegated recovery in a cluster or a single server recovery after a crash, if such logs are stored in a database.

Storing transaction logs as a set of files leads to a contention in file access under heavy load. Also, in a clustered environment, storing transaction logs on a file system requires mounting a shareable file system (NFS) so that it can be accessible by all instances in a cluster for a delegated transaction recovery.

3.2. Justification:

Useful feature

4. Technical Description:
4.1. Details:

A very limited support for storing transaction logs in a database will be extended to a full parity with all features available when such logs are stored in a file system.

In addition to the setup described in the current documentation (http://download.oracle.com/docs/cd/E18930_01/html/821-2416/beanq.html#gcmam), the following features will be provided:
a) Automatic table creation will be done at the time of XA transaction service bootstrap. It will also be possible for the user to create the table themselves. Failed automatic table creation will not be considered an error.
b) To allow more database types to be supported out of the box, column type VARCHAR will be used for the LOCALTID column.
c) If the users choose not to create a separate non-transactional jdbc resource for the logging, but reference an existing transactional resource but use non-transactional connections for the INSERT statements, a system property "com.sun.jts.dblogging.use.nontx.connection.for.add" set to "true" (-Dcom.sun.jts.dblogging.use.nontx.connection.for.add=true) will be used.

4.2. Bug/RFE Number(s):

17405

4.3. In Scope:

Manual and automated delegated transaction recovery for transaction logs stored in a database

4.4. Out of Scope:

Automatic database type detection and ability to generated DDL and SQL statements for all otherwise supported databases.

4.5. Interfaces:
4.5.1 Public Interfaces

a) User-visible setup will slightly change

b) Interfaces in transaction/internal-api module might need improvements to fix deadlock during transaction recovery on server restart

4.5.2 Private Interfaces

No change from GlassFish 3.1.1
4.5.3 Deprecated/Removed Interfaces:

N/A
4.6. Doc Impact:

Will need to update the corresponding section in the "Transaction Logging" chapter to reflect the updated setup.

4.7. Admin/Config Impact:

Relax requirement for recover-transactions CLI to provide --transactionlogdir value for delegated recovery (this parameter is not used for database based transaction logs).

4.8. HA Impact:

N/A
4.9. I18N/L10N Impact:

Minimal. Only new log and exception messages will need to be localized.

4.10. Packaging, Delivery & Upgrade:
4.10.1. Packaging

Will follow GlassFish 3.1.2 Packaging.

4.10.2. Delivery

Will be delivered as part of GlassFish 3.1.2

4.10.3. Upgrade and Migration:

Upgrade from an existing table will not be supported due to the table DDL changes.

4.11. Security Impact:

N/A
4.12. Compatibility Impact

Column type VARCHAR will be used for the LOCALTID column

4.13. Dependencies:

No external dependencies.
4.13.1 Internal Dependencies

N/A

4.13.2 External Dependencies

N/A
4.14. Testing Impact:

   * Regression QA tests will be executed.
   * New development test setup for cluster with 3 instances and failover behavior will need to be added.

5. Reference Documents:

6. Schedule:
6.1. Projected Availability:

Indicate which milestones from the current schedule the project
will be:

 TBD